home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / pascal / tpu2asm.zip / TPU2ASM.DOC < prev    next >
Text File  |  1990-10-29  |  16KB  |  313 lines
  1. ┌─────────────────────────────────────────────────────────────────────────────┐
  2. │                                                                             │
  3. │                                 Documentation for                           │
  4. │                                                                             │
  5. │                                    TPU2ASM.EXE                              │
  6. │                                                                             │
  7. │                            A symbolic disassembler for                      │
  8. │                          Turbo Pascal version 5.0 units                     │
  9. │                                                                             │
  10. │                       Copyright (C) 1989 by Per Bent Larsen                 │
  11. │                                All rights reserved                          │
  12. │                                                                             │
  13. │                              Version 1.0, March 1989                        │
  14. │                                                                             │
  15. └─────────────────────────────────────────────────────────────────────────────┘
  16.  
  17.  
  18. What it is
  19. ──────────────────────────────────────────────────────────────────────────────
  20. TPU2ASM is a symbolic disassembler capable of extracting compiled code from a
  21. version 5.0 Turbo Pascal TPU file. The output is a TASM compatible assembly
  22. file.
  23.  
  24.  
  25. What it can be used for
  26. ──────────────────────────────────────────────────────────────────────────────
  27. The utility can be used as an aid in developing EXTERNAL procedures and func-
  28. tions for Turbo Pascal, allowing the programmer to write a template function or
  29. procedure with parameter and local variable allocation set up automatically by
  30. the compiler.
  31.  
  32. You can also choose to write the entire routine in pascal and then do manual
  33. optimization on the code produced by the compiler. The code generated by Turbo
  34. Pascal leaves much room for improvement as you will soon find out.
  35.  
  36. Another use for the utility is studying the code generated by the compiler to
  37. determine which pascal constructs are preferable to others in terms of execu-
  38. tion speed and code size. You'll be surprised.
  39.  
  40. Finally this utility makes it theoretically possible to convert an entire pro-
  41. gram to assembler thus allowing you to link it with other languages like C or
  42. PROLOG. To do this you must have the Turbo Pascal Runtime Library Source avai-
  43. lable from Borland Int'l. It requires a conversion of the RTL into pure assem-
  44. bler. Be warned - this may not be a trivial process.
  45.  
  46.  
  47. What it isn't
  48. ──────────────────────────────────────────────────────────────────────────────
  49. This utility was not meant to be a reverse engineering tool, though it can be
  50. used as such to a limited extend. All references are shown symbolically and
  51. when a symbol is not known due to lack of information in the symbol tables, the
  52. program does not attempt to make a symbol of it's own. When TPU2ASM can not
  53. find the symbol for a reference, it is always because one ore more units were
  54. compiled with $D- or $L-. References that can not be resolved symbolically are
  55. left as ???? in the output file. Exceptions to this are items which are always
  56. unnamed like the CS constant block. These items are named by TPU2ASM.
  57.  
  58.  
  59. How to use it
  60. ──────────────────────────────────────────────────────────────────────────────
  61. The program is invoked from the DOS prompt as follows:
  62.  
  63.   TPU2ASM UnitName OutputFile [Procedure|Function]
  64.  
  65. The UnitName is of course the name of the unit to extract from. You should not
  66. specify an extension. The unit is assumed to be in a file with the same name
  67. and a TPU extension or in TURBO.TPL.
  68.  
  69. The OutputFile specifies where the assembly should go to. The extension de-
  70. faults to ASM. If the file exists you are prompted for overwrite permission.
  71.  
  72. The last parameter is an optional procedure or function name. If you omit this
  73. entry it is assumed that you wish to extract all procedures and functions from
  74. the unit. You are prompted for verification in this case. Only global procedu-
  75. res and functions can be extracted. This is because local routines always have
  76. an access link to the local data in the owner routine, more on that later. Glo-
  77. bal routines will pull all their local routines into the disassembly as well.
  78.  
  79.  
  80. Limitations
  81. ──────────────────────────────────────────────────────────────────────────────
  82. TPU2ASM reads the symbol table from all referenced units into RAM. This imposes
  83. a restriction on the number and size of units referenced. However I haven't
  84. encountered any heap overflows on my 640K machine even when extracting from
  85. very large units with many references. Only symbol tables are kept in RAM, not
  86. entire units.
  87.  
  88. Extracting EXTERNAL routines can not always be done correctly. A Turbo Pascal
  89. procedure or function is always stored in the TPU as a single block. If the
  90. entry point is zero, the entire block is known to be executable code, otherwise
  91. the first part of the block is known to be CS constants (literal data like
  92. strings, sets, range checking values and so on) and the rest is executable
  93. code. Not so with externals. OBJ files can have multiple routines in them and
  94. they can have data areas anywhere in both the data and code segments. Turbo
  95. Pascal does not keep track of anything but the data size, the code size (inclu-
  96. ding CS data) and the entry points for the PUBLIC routines. When extracting EX-
  97. TERNALS from a TPU, TPU2ASM initially assumes that the entire block up to the
  98. entry point is data. When it does the disassembly, it checks for jumps and
  99. calls into the assumed data part. If such a branch is encountered, the disas-
  100. sembly process is restarted with this new address as starting point. This pro-
  101. cess is repeated as required. The consequence of this strategy is that if the
  102. external module has multiple PUBLIC symbols, you may get the same routine in
  103. the output more than once. Also any data after the starting point is assumed
  104. to be code.
  105.  
  106. TPU2ASM attempts to create an ASM file which can be compiled directly by TASM.
  107. However TPU2ASM does not attempt to solve symbolic conflicts between Turbo
  108. Pascal and TASM. There are two types of errors likely to occur in an ASM file
  109. produced by TPU2ASM: Either you have used an identifier name in you pascal pro-
  110. gram which happens to be a reserved word in TASM, or you have local and global
  111. identifiers with duplicate names. TASM does not handle scope concepts as does
  112. pascal. Both types of errors can be dealt with by choosing other identifier
  113. names in the pascal source.
  114.  
  115.  
  116. Symbols defined by TPU2ASM
  117. ──────────────────────────────────────────────────────────────────────────────
  118. When disassembling a code or data reference, TPU2ASM uses the symbol from the
  119. pascal source if it's available. Data and code external to the unit is referen-
  120. ced by the pascal symbol directly. Parameters and local variables have a BP
  121. EQUate immediately following the PROC header, and all subsequent references are
  122. done with the EQU symbol. All local variables and labels are preceded with @@
  123. to avoid conflict with other PROCs. When disassembling functions, TPU2ASM de-
  124. fines a BP EQUate to $RESULT which denotes the function result buffer. When
  125. disassembling local routines, an additional BP symbol $LINK is defined, which
  126. denotes the Base Page link to the calling routines local data. Local label
  127. names are defined as @@<number>: , the exception being when call or jumps out-
  128. side the PROC-ENDP pair is encountered (this can only occur in EXTERNALS). In
  129. this case the label names are defined as <proc name><number>$. If the unit has
  130. initialization code, it is given the name <UnitName>$INIT.
  131.  
  132. TASM offers a TPASCAL model directive to simplify creation of EXTERNALs for
  133. Turbo Pascal. TPU2ASM does not use it, however. This is to give you complete
  134. flexibility to change the code. When you use TPASCAL, TASM always sets up a
  135. so called base frame, which is not always necessary.
  136.  
  137.  
  138. References to the SYSTEM unit
  139. ───────────────────────────────────────────────────